home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 23 / Amiga Format AFCD23 (Feb 1998, Issue 107).iso / -coverdisks- / subsdisk / subs.dms / subs / gui4cli.LZX / Gui4Cli / Docs / wbpath / wbpath.h < prev    next >
C/C++ Source or Header  |  2003-12-15  |  3KB  |  114 lines
  1. /*
  2. ** WbPath.h - clone the Workbench process's command path.
  3. ** Copyright © 1994 by Ralph Babel. Permission granted to
  4. ** distribute this file in conjunction with »WbPath.o« and
  5. ** »PathTest.c« in unmodified form and to use the associated
  6. ** object module »WbPath.o«, provided that this file,
  7. ** »WbPath.o«, and »PathTest.c« accompany the resulting
  8. ** program. All other rights reserved.
  9. */
  10.  
  11. #ifndef WBPATH_H
  12. #define WBPATH_H
  13.  
  14. /*** included files ***/
  15.  
  16. #ifndef EXEC_EXECBASE_H
  17. #include <exec/execbase.h>
  18. #endif
  19.  
  20. #ifndef DOS_DOS_H
  21. #include <dos/dos.h>
  22. #endif
  23.  
  24. #ifndef DOS_DOSEXTENS_H
  25. #include <dos/dosextens.h>
  26. #endif
  27.  
  28. #ifndef WORKBENCH_STARTUP_H
  29. #include <workbench/startup.h>
  30. #endif
  31.  
  32. /*
  33.  
  34. When a program is launched via the »Execute Command ...«
  35. menu item provided by Workbench, Workbench passes the CLI
  36. command path that was active at the time LoadWb was invoked
  37. to the application. Regular Workbench processes, however, do
  38. not operate in a CLI environment, so they cannot inherit the
  39. Workbench path, and new shells spawned by such processes via
  40. SystemTagList() start with an »empty« path (i.e. just »C:«
  41. and the current directory).
  42.  
  43. The function CloneWorkbenchPath() creates a local copy of
  44. the current Workbench path, usually for the purpose of it
  45. being passed to SystemTagList() or to CreateNewProc() via
  46. the NP_Path tag; the WBStartup parameter passed to
  47. CloneWorkbenchPath() must be valid and non-NULL. The path is
  48. deallocated automatically by the OS upon the termination of
  49. the newly created process; if the CreateNewProc() or
  50. SystemTagList() call fails, however, the cloned path must be
  51. freed explicitly by calling FreeWorkbenchPath().
  52.  
  53. The actual return value of CloneWorkbenchPath() need/must
  54. not be checked for zero (the Workbench path may be empty
  55. after all), and all possible results may safely be used with
  56. NP_Path or passed to FreeWorkbenchPath(). The result may
  57. also be zero if the Workbench path could not be obtained for
  58. any reason, and the path may be truncated if an error
  59. occurred or if the path was updated via »LoadWb NEWPATH«
  60. while it was being cloned.
  61.  
  62. These functions may safely be called under all versions of
  63. the Amiga's OS, although prior to 2.0 they usually don't do
  64. a whole lot, and the dos.library functions they are usually
  65. used with did not exist prior to 2.0.
  66.  
  67. WARNING: Accessing another process's CLI path is an
  68. unsupported operation, and although CloneWorkbenchPath()
  69. tries to take all possible precautions, all bets are off
  70. should the Workbench path become inconsistent while it is
  71. being cloned. (This is not currently the case, though.)
  72.  
  73. Further information can be found in the Amiga Guru Book on
  74. pages 400 and 571 f. The Amiga Guru Book is available from:
  75.  
  76. Hirsch & Wolf OHG
  77. Mittelstraße 33
  78. D-56564 Neuwied
  79. Germany
  80. Voice: +49 (2631) 8399-0
  81. Fax:   +49 (2631) 8399-31
  82.  
  83. Periscope Discs, Tapes, Books
  84. Attn: Cody Lee
  85. 1717 West Kirby Avenue
  86. Champaign, IL 61821
  87. USA
  88. Voice: +1 (217) 398 4237
  89. Fax:   +1 (217) 398 4238
  90. E-Mail: <periscope@cei.com>
  91.  
  92. Someware
  93. 27 rue Gabriel Péri
  94. 59186 Anor
  95. France
  96. Voice: +33 27596000
  97. Fax:   +33 27595206
  98.  
  99. */
  100.  
  101. /*** macros ***/
  102.  
  103. #define CloneWorkbenchPath(sm) cloneWorkbenchPath(SysBase, DOSBase, sm)
  104. #define FreeWorkbenchPath(path) freeWorkbenchPath(SysBase, DOSBase, path)
  105.  
  106. /*** symbol export ***/
  107.  
  108. BPTR __stdargs cloneWorkbenchPath(struct ExecBase *,
  109.  struct DosLibrary *, struct WBStartup *);
  110. void __stdargs freeWorkbenchPath(struct ExecBase *,
  111.  struct DosLibrary *, BPTR);
  112.  
  113. #endif /* WBPATH_H */
  114.